Making Your First API Calls
Assumptions and Prerequisites
This chapter assumes that you are somewhat familiar with REST APIs.
You also need:
· a Cloud tenant
· The URL to your Cloud system
· Admin user name and password for the tenant
· One of the following tools installed:
o Postman REST Client installed on Chrome web browser
o DEV HTTP Client installed on Chrome web browser
o RESTClient installed on Firefox browser
o cURL installed on your computer
In this guide, we will use Postman REST Client and cURL for our examples.
Making a Few Simple Calls
In this section, we’ll perform the following calls:
· Get account information for all existing users.
· Create a new user.
Getting Account Information
This call returns information about all the users in the current tenant.
Using Postman REST Client
To get account information for all users on your Cloud system:
1. Start Google Chrome and then select Postman – REST Client:
A Postman tab appears.
2. Enter http://url_to_your_cloud_environment/api/v1/account/, select GET from the Operations dropdown menu, and then click the Basic Auth tab:
Note: Replace url_to_your_ cloud_environment with the actual URL to your environment.
The Basic Auth tab appears.
3. Enter your admin username and password, click Refresh headers, and then click Send:
Note: The Cloud Integration API uses basic authentication.
The response appears in the Postman’s lower pane:
{
"errors": null,
"result": {
"totalCount": 2,
"queryTime": 2,
"searchResults": [
{
"id": 10000,
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"displayName": null,
"firstName": null,
"lastName": null,
"ldapServerId": null,
"uid": "[email protected]",
"emailAddress": "[email protected]",
"username": null,
"accountSource": "LOCAL",
"inviteState": "None",
"inviteResendCount": 0,
"inviteLastSentAt": null,
"locale": null,
"enabled": false,
"locked": false,
"superUser": false,
"termsAccepted": false,
"passwordExpiresAt": null,
"distinguishedName": null,
"objectGuid": null,
"trash": false,
"mutable": false,
"loginFailureCount": 0,
"loginSuccessAt": null,
"passwordHistory": "{\"passwords\":[]}",
"actionExceptionCodes": null,
"groups": [
"All Users"
],
"deviceCount": 0
},
{
"id": 10001,
"createdAt": null,
"createdBy": null,
"modifiedAt": null,
"modifiedBy": null,
"displayName": null,
"firstName": "FirstName0001",
"lastName": "LastName0001",
"ldapServerId": null,
"uid": "[email protected]",
"emailAddress": "[email protected]",
"username": null,
"accountSource": "LOCAL",
"inviteState": "None",
"inviteResendCount": 0,
"inviteLastSentAt": null,
"locale": null,
"enabled": false,
"locked": false,
"superUser": false,
"termsAccepted": false,
"passwordExpiresAt": null,
"distinguishedName": null,
"objectGuid": null,
"trash": false,
"mutable": false,
"loginFailureCount": 0,
"loginSuccessAt": null,
"passwordHistory": "{\"passwords\":[]}",
"actionExceptionCodes": null,
"groups": [
"All Users"
],
"deviceCount": 0
}
],
"offset": 0,
"facetedResults": {
"TERMSACCEPTED": {
"true": 0,
"false": 2
},
"ACCOUNTGROUP": {
"All Users": 2
},
"INVITESTATE": {
"Expired": 0,
"Completed": 0,
"None": 2,
"Pending": 0
}
}
}
}
Using cURL
This section describes how to use a Windows 7 cURL client to get account information for all users on your Cloud system.
To get account information for all users on your Cloud system:
4. Open a Command Prompt window as illustrated below:
A Command Prompt window appears.
5. Enter the following command in the Command Prompt window, replacing admin_username with the actual admin username, admin_password with the actual admin user password, and URL_to_your_cloud_environment with your actual Cloud URL:
curl -u admin_username:admin_password –kv "https://URL_to_your_cloud_environment/api/v1/account/"
For example:
curl -u [email protected]:Pi3man11 –kv
"https://[Cloud]/api/v1/account/"
The response appears:
Creating a User
Using Postman REST Client
This call creates a new user in the current tenant.
1. Start Google Chrome and then select Postman – REST Client:
A Postman tab appears.
2. Configure the Postman tab as illustrated below:
Note: Replace url_to_your_cloud_environment with the actual URL to your environment.
The Basic Auth tab appears.
3. Enter your admin username and password, click Refresh headers, and then click Send:
Note: If your authentication credentials already exist from the previous call, the you can skip steps 1 and 2 in the illustration above.
Postman indicates a successful call and posts the response the lower pane:
{
"errors": null,
"result": {
"id": 10629,
"createdAt": null,
"createdBy": 10001,
"modifiedAt": null,
"modifiedBy": 10001,
"displayName": null,
"firstName": null,
"lastName": null,
"ldapServerId": null,
"uid": "[email protected]",
"emailAddress": "[email protected]",
"username": null,
"accountSource": "LOCAL",
"inviteState": null,
"inviteResendCount": 0,
"inviteLastSentAt": null,
"locale": "en_US",
"enabled": false,
"locked": false,
"superUser": false,
"termsAccepted": false,
"passwordExpiresAt": null,
"distinguishedName": null,
"objectGuid": null,
"trash": false,
"mutable": true,
"loginFailureCount": 0,
"loginSuccessAt": null,
"passwordHistory": "{\"passwords\":[]}",
"actionExceptionCodes": null
}
}
Using cURL
This section describes how to use a Windows 7 cURL client to create a new user on your Cloud system.
To create a new user on your Cloud system:
1. Open a Command Prompt window as illustrated below:
A Command Prompt window appears.
2. Enter the following command in the Command Prompt window, replacing admin_username with the actual admin username, admin_password with the actual admin user password, and URL_to_your_cloud_environment with your actual Cloud URL:
curl -u admin_username:admin_password -kv "https://URL_to_your_cloud_environment/api/v1/[email protected]&[email protected]&accountSource=Local" -d ''
For example:
curl -u [email protected]:Pi3man11 –kv "https://[Cloud]/api/v1/[email protected]&[email protected]&accountSource=Local" –d ''
The response appears:
